/*
 * Copyright (c) 2021-2022 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup huks
 * @{
 *
 * @brief 描述huks向应用提供密钥库能力，包括密钥管理及密钥的密码学操作等功能。
 * 管理的密钥可以由应用导入或者由应用调用HUKS接口生成。
 *
 * @since 8
 * @version 1.0
 */

/**
 * @file native_huks_api.h
 *
 * @brief 声明用于访问huks的API。
 *
 * @since 8
 * @version 1.0
 */

#ifndef _NATIVE_HUKS_API_H_
#define _NATIVE_HUKS_API_H_

#include "native_hks_type.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 获取huks的版本信息。
 *
 * @param sdkVersion 用于存储获取到的版本信息。
 * @return 返回执行的状态代码。
 * @since 8
 * @version 1.0
 */
OH_HUKS_API_EXPORT int32_t OH_Huks_GetSdkVersion(struct OH_Huks_Blob *sdkVersion);

/**
 * @brief 生成密钥。
 *
 * @param keyAlias 表示给要生成的密钥取的别名。
 * @param paramSetIn 表示生成密钥需要的输入参数集。
 * @param paramSetOut 生成密钥为临时类型时存放着密钥数据；非临时类型可为空。
 * @return 返回执行的状态代码。
 * @since 8
 * @version 1.0
 */
OH_HUKS_API_EXPORT int32_t OH_Huks_GenerateKey(const struct OH_Huks_Blob *keyAlias,
    const struct OH_Huks_ParamSet *paramSetIn, struct OH_Huks_ParamSet *paramSetOut);

/**
 * @brief 导入密钥。
 *
 * @param keyAlias 表示给要导入的密钥取的别名。
 * @param paramSet 表示导入密钥需要的输入参数集。
 * @param key 表示导入的密钥数据。
 * @return 返回执行的状态代码。
 * @since 8
 * @version 1.0
 */
OH_HUKS_API_EXPORT int32_t OH_Huks_ImportKey(const struct OH_Huks_Blob *keyAlias,
    const struct OH_Huks_ParamSet *paramSet, const struct OH_Huks_Blob *key);

/**
 * @brief 导出公钥。
 *
 * @param keyAlias 表示要导出公钥对应的密钥别名。
 * @param paramSet 表示导出公钥需要的输入参数集。
 * @param key 表示要导入的密钥数据。
 * @return 返回执行的状态代码。
 * @since 8
 * @version 1.0
 */
OH_HUKS_API_EXPORT int32_t OH_Huks_ExportPublicKey(const struct OH_Huks_Blob *keyAlias,
    const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_Blob *key);

/**
 * @brief 删除密钥。
 *
 * @param keyAlias 表示要删除密钥的别名。
 * @param paramSet 表示要删除密钥需要的输入参数集。
 * @return 返回执行的状态代码。
 * @since 8
 * @version 1.0
 */
OH_HUKS_API_EXPORT int32_t OH_Huks_DeleteKey(const struct OH_Huks_Blob *keyAlias,
    const struct OH_Huks_ParamSet *paramSet);

/**
 * @brief 获取生成密钥时的参数集。
 *
 * @param keyAlias 表示要获取参数集的密钥别名
 * @param paramSetIn 表示要获取参数集需要的输入参数集。
 * @param paramSetOut 表示获取到的输出参数集。
 * @return 返回执行的状态代码。
 * @since 8
 * @version 1.0
 */
OH_HUKS_API_EXPORT int32_t OH_Huks_GetKeyParamSet(const struct OH_Huks_Blob *keyAlias,
    const struct OH_Huks_ParamSet *paramSetIn, struct OH_Huks_ParamSet *paramSetOut);

/**
 * @brief 查询存储中密钥是否存在。
 *
 * @param keyAlias 表示密钥别名。
 * @param paramSet 表示查询需要的输入参数集。
 * @return 返回执行的状态代码。
 * @since 8
 * @version 1.0
 */
OH_HUKS_API_EXPORT int32_t OH_Huks_KeyExist(const struct OH_Huks_Blob *keyAlias,
    const struct OH_Huks_ParamSet *paramSet);

/**
 * @brief 使用密钥对数据进行算法操作的init动作。
 *
 * @param keyAlias 表示使用密钥的别名。
 * @param paramSet 表示init需要的输入参数集。
 * @param handle 表示使init、update、finish和abort联系起来的输出特征值。
 * @return 返回执行的状态代码。
 * @since 8
 * @version 1.0
 */
OH_HUKS_API_EXPORT int32_t OH_Huks_Init(const struct OH_Huks_Blob *keyAlias,
    const struct OH_Huks_ParamSet *paramSet, struct OH_Huks_Blob *handle);

/**
 * @brief 使用密钥对数据进行算法操作的update动作。
 *
 * @param handle 表示使init、update、finish和abort联系起来的输入特征值。
 * @param paramSet 表示update需要的输入参数集。
 * @param inData 表示要处理的输入数据，如果数据过大，可分片多次调用update。
 * @param outData 表示经过算法操作处理后的输出数据。
 * @return 返回执行的状态代码。
 * @since 8
 * @version 1.0
 */
OH_HUKS_API_EXPORT int32_t OH_Huks_Update(const struct OH_Huks_Blob *handle,
    const struct OH_Huks_ParamSet *paramSet, const struct OH_Huks_Blob *inData, struct OH_Huks_Blob *outData);

/**
 * @brief 使用密钥对数据进行算法操作的finish动作。
 *
 * @param handle 表示使init、update、finish和abort联系起来的输入特征值。
 * @param paramSet 表示finish需要的输入参数集。
 * @param inData 表示要处理的输入数据。
 * @param outData 表示经过算法操作处理后的输出数据。
 * @return 返回执行的状态代码。
 * @since 8
 * @version 1.0
 */
OH_HUKS_API_EXPORT int32_t OH_Huks_Finish(const struct OH_Huks_Blob *handle,
    const struct OH_Huks_ParamSet *paramSet, const struct OH_Huks_Blob *inData, struct OH_Huks_Blob *outData);

/**
 * @brief update、finish异常退出的清理动作。
 *
 * @param handle 表示使init、update、finish和abort联系起来的输入特征值。
 * @param paramSet 表示abort需要的输入参数集。
 * @return 返回执行的状态代码。
 * @since 8
 * @version 1.0
 */
OH_HUKS_API_EXPORT int32_t OH_Huks_Abort(const struct OH_Huks_Blob *handle,
    const struct OH_Huks_ParamSet *paramSet);

#ifdef __cplusplus
}
#endif

#endif /* NATIVE_HUKS_API_H */
